# dev.client

配置 Rsbuild 在开发过程中注入的 client 代码，可以用于设置热更新对应的 WebSocket URL。

- **类型：**

```ts
type Client = {
  // WebSocket 请求的协议名称
  protocol?: 'ws' | 'wss';
  // WebSocket 请求的路径
  path?: string;
  // WebSocket 请求的端口号
  port?: string | number;
  // WebSocket 请求的 host
  host?: string;
  // WebSocket 请求断开后的最大重连次数
  reconnect?: number;
  // 当出现编译错误时，是否在浏览器中显示 error overlay
  overlay?: boolean;
};
```

- **默认值：**

```js
const defaultConfig = {
  path: '/rsbuild-hmr',
  // 默认为 "location.port"
  port: '',
  // 默认为 "location.hostname"
  host: '',
  // 默认为 "location.protocol === 'https:' ? 'wss' : 'ws'""
  protocol: undefined,
  reconnect: 100,
  overlay: true,
};
```

## 配置 WebSocket URL

默认情况下，当你启动 dev server，并访问 `http://localhost:3000/` 时，页面上会发起一个 WebSocket 请求，指向 `ws://localhost:3000/rsbuild-hmr`，使页面与开发服务器建立连接。

在某些开发场景下，你可能需要调整 WebSocket URL，来保证 WebSocket 请求能够正确连接。

比如当你使用代理工具进行开发时，实际访问的可能是一个线上域名，此时你可以手动配置 `dev.client`，将 WebSocket URL 指向本地的开发服务器。下面是一个示例，WebSocket 请求的地址为 `ws://127.0.0.1:3000/rsbuild-hmr`：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      protocol: 'ws',
      // 通常使用 `127.0.0.1`，可以避免跨域请求被浏览器拦截
      host: '127.0.0.1',
      port: 3000,
    },
  },
};
```

### 端口号占位符

Rsbuild server 监听的端口号可能会发生变更。比如，当端口被占用时，Rsbuild 会自动递增端口号，直至找到一个可用端口。

为了避免端口变化导致 `client.port` 失效，你可以使用以下方法之一：

- 开启 [server.strictPort](/config/server/strict-port)。
- 使用 `<port>` 占位符来指代当前端口号，Rsbuild 会将占位符替换为实际监听的端口号。

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};
```

## hot-update 文件

在热更新过程中，页面会发起 GET 请求来获取 hot-update 文件，包括 `*.hot-update.json` 和 `*.hot-update.js`。这些文件包含了热更新所需的信息，比如被更新的模块、模块的代码等。

hot-update 文件属于静态资源，如果你需要配置 hot-update 文件的 URL，请使用 [dev.assetPrefix](/config/dev/asset-prefix) 选项。

## Error overlay

通过 `dev.client.overlay` 选项，可以选择是否启用 error overlay。

默认情况下，当编译发生错误时，Rsbuild会在浏览器中显示 error overlay，并提供错误信息和错误堆栈：

![error overlay](https://assets.rspack.rs/rsbuild/assets/rsbuild-error-overlay.png)

如果需要禁用 error overlay，可以将其设置为 `false`：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      overlay: false,
    },
  },
};
```

:::tip
Error overlay 功能需要当前浏览器版本支持 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)。在不支持的浏览器中，overlay 不会展示。
:::
